cvtF Conversion Method

The cvtF attribute enables you to specify a conversion keyword by which to convert source data into a different target format. This enables the consumption of field-device data in a format acceptable to a CygNet SCADA host.

The attribute cvtF is defined in data group elements in a device template file (that is, a device definition). The cvtF attribute is not restricted to a single protocol like cvtRef is. Applicable supporting attributes (that is, parameters) are typically defined in the same data group element as the cvtF value they support. For example, Scale requires that sourceType be defined in the same data group element as Scale.

cvtF values typically apply to all EIEs; when exceptions occur, they are called out. For example, sometimes a cvtF value is specific to a single EIE, and sometimes an EIE cannot make use of a cvtF value. Data converted by a cvtF conversion method can be reformatted by using a reference method.

Example

<DateTime niceName="Date and Time" canSend="true" uccSend="true" dgProtocol="Internal"> <dgElements secLev="4"> <DeviceTime desc="Device DateTime" type="r8"/> <HostTime desc="Host DateTime" type="r8"/> <EPTime desc="Raw Device Time" type="ui4" hidden="true" paramID="3" cvtF="3ByteTime"/> <EPDate desc="Raw Device Date" type="r8" hidden="true" paramID="4" cvtF="3ByteDate"/> </dgElements> </DateTime>

See the following conversion methods for more information:

cvtF Conversion Methods
Byte Conversions	Date-Time Conversions	Numeric Conversions
ConvertBigEndianToLittleEndian ConvertCopyBytes ConvertStringBytes CopyBytes ReverseBytes WordSwap	3ByteDate 3ByteTime 3ByteTimeToString BartonTimeD BartonTimeS BsapDateConv DevHour Efm3000DateConv HrMn2Sec HrMnSec2Sec HrSMn2Sec JTime JTimeD JTimeS LufkinUInt2DateTimeString NuFloDateConv ProS2100ConvertDatetime ProS2100ConvertDateTimeStr ProSoftConvertDatetime ProSoftConvertDateTimeStr RealFloDateConv SamDeviceDateTime SixByteDateTime TfTime TimeMS TimeSeconds TimeString UInt2DateTimeString	Convert12BitFloat Convert31BitSCompF ConvertBCD DecFloat HpFloat LufkinScaleAnalog LufkinScaleLoad Mod10K NuFloFWVerConv NuFloRegTabVerConv ProSoftAccum OneByteBCDToIntelInt Scale TfReg TfStream ThreeByteBCDToInt TLP TwoByteBCDToInt Version

Byte Conversions

The following cvtF conversion functions all enable the conversion from one byte format to another.

ConvertBigEndianToLittleEndian

ConvertBigEndianToLittleEndian reverses bytes from the field device before processing them. The following attributes apply to this cvtF method:

• parm1 — Size in bytes of the data item to copy. This parameter is required. (You can alternatively use len to define size in bytes or type when type applies and adequately implies the length of the data in bytes.) Acceptable values are 1, 2, 4, and 8.

ConvertCopyBytes

See CopyBytes.

ConvertStringBytes

ConvertStringBytes takes a string of two-byte characters and converts the string to a string of single-byte characters using only the high byte or low byte of each character. The following attributes apply to this cvtF method:

• lowByte — See lowByte.
• nullPad — See nullPad.
• spacePad — See spacePad.

CopyBytes

CopyBytes copies bytes into a data group element in the format in which they originated at the field device. The following attributes apply to this cvtF method:

• parm1 — Size in bytes of the data item to copy. This parameter is required. (You can alternatively use len to define size in bytes or type when type applies and adequately implies the length of the data in bytes.) Acceptable values are 1, 2, 4, and 8.

ReverseBytes

See ConvertBigEndianToLittleEndian.

WordSwap

wordSwap reverses the order of the words in a 4-byte item or 8-byte item without reversing the bytes in each word.

 

The following attributes apply to this cvtF method:

• byteOrder — See byteOrder.

Date-Time Conversions

The following cvtF conversion functions all enable the conversion from one date-time format to another.

3ByteDate

3ByteDate converts three one-byte integer date values (where one byte represents years, one byte represents months, and one byte represents days) to a Microsoft standard date-time format (COleDateTime) value. For example, hex 17 0C 0D with a formatDate value of DDMMYY would display as 23 12 13. The following attributes apply to this cvtF method:

• formatDate — Optional. See formatDate.

3ByteTime

3ByteTime converts three one-byte integer time values (where one byte represents hours, one byte represents minutes, and one byte represents seconds) to a total number of seconds. There are no directly applicable attributes or parameters.

3ByteTimeToString

3ByteTimeToString converts three one-byte integer time values (where one byte represents hours, one byte represents minutes, and one byte represents seconds) to a string in the format HH:MM:SS. The following attributes apply to this cvtF method:

• len="8" — Required parameter. See len.

BartonTimeD

BartonTimeD converts six one-byte integer date-time values (where one byte represents years, one byte represents months, one byte represents days, one byte represents hours, one byte represents minutes, and one byte represents seconds) to a Microsoft standard date-time format (COleDateTime) value. There are no directly applicable attributes or parameters.

BartonTimeS

BartonTimeS converts six one-byte integer date-time values (where one byte represents years, one byte represents months, one byte represents days, one byte represents hours, one byte represents minutes, and one byte represents seconds) to a Microsoft standard date-time format (COleDateTime) value. Then it formats the COleDateTime value to a string in the format %Y/%m/%d %H:%M:%S. There are no directly applicable attributes or parameters.

BsapDateConv

BsapDateConv converts two consecutive two-byte big-endian values in Bristol Babcock time (that is, Julian time) format to a double-precision floating-point value. Specific to BSAP EIE devices. The following attribute applies to this cvtF method:

• parm1 — Specifies the format of the destination date-time value. The value must be a non-negative whole number.

DevHour

DevHour converts a source data value from a four-byte integer that represents the hour of the day in UTC to an unsigned four-byte integer hour in local time as specified on the remote device. There are no directly applicable attributes or parameters.

Efm3000DateConv

Efm3000DateConv converts a source date-time value in number of seconds since January 1, 1970 (time_t) to a Microsoft standard date-time format (COleDateTime) value. (You can format the converted value using a reference data group element that defines a ref attribute and format attribute in combination.) There are no directly applicable attributes or parameters.

HrMn2Sec

HrMn2Sec converts a four-byte integer time value (where two bytes represent hours and two bytes represent minutes) to total seconds. Only whole hour and whole minute values apply; seconds that might have been part of the source time are dropped. There are no directly applicable attributes or parameters.

HrMnSec2Sec

HrMnSec2Sec converts a four-byte integer time value (where two bytes represent hours, one byte represents minutes, and one byte represents seconds) to total seconds. The following attributes apply to this cvtF method:

• readOnly — Used to prohibit writing a converted value to the field device. The value must be set to true.

HrSMn2Sec

HrSMn2Sec converts a four-byte integer time value (where two bytes represent hours and two bytes represent scaled minutes) to total seconds. Only whole hour and whole minute values apply; seconds that might have been part of the source time are dropped. The following attributes apply to this cvtF method:

• parm1 — Specifies the scale factor to apply to the minutes bytes. The value must be a non-negative number.
• readOnly — Used to prohibit writing a scaled value to the field device. The value must be set to true.

JTime

JTime converts two consecutive two-byte big-endian values in Bristol Babcock time (that is, Julian time) format to a Microsoft standard date-time format (COleDateTime) value. (The first two source bytes represent days, and the next two source bytes represent second increments.) The following attributes apply to this cvtF method:

• parm1 — Specifies the format of the destination date-time value. The value must be a non-negative whole number. To output a COleDateTime value, set to 0. To output a string as described by JTimeS, set to 1.

JTimeD

JTimeD converts two consecutive two-byte big-endian values in Bristol Babcock time (that is, Julian time) format to a Microsoft standard date-time format (COleDateTime) value. (The first two source bytes represent days, and the next two source bytes represent second increments.) There are no directly applicable attributes or parameters.

JTimeS

JTimeS converts two consecutive two-byte big-endian values in Bristol Babcock time (that is, Julian time) format to a Microsoft standard date-time format (COleDateTime) value. (The first two source bytes represent days, and the next two source bytes represent second increments.) Then it formats the COleDateTime value to a string in the format %Y/%m/%d %H:%M:%S. There are no directly applicable attributes or parameters.

LufkinUInt2DateTimeString

LufkinUInt2DateTimeString converts an unsigned integer time_t value (seconds since Jan 1, 1970) to a date-time string in the following format: DD-MM-YYYY HH:mm:ss. If no time values are returned, none are displayed. Specific to Lufkin MPC/RPC EIE and Lufkin SAM EIE devices. There are no directly applicable attributes or parameters.

NuFloDateConv

NuFloDateConv converts from a NuFlo-specific format to a Microsoft standard date-time format (COleDateTime) value. There are no directly applicable attributes or parameters.

ProS2100ConvertDatetime

ProS2100ConvertDatetime converts a word-swapped, big-endian, 32-bit UNIX time in UTC to a Microsoft standard date-time format (COleDateTime) value. There are no directly applicable attributes or parameters.

ProS2100ConvertDateTimeStr

ProS2100ConvertDateTimeStr converts a word-swapped, big-endian, 32-bit UNIX time in UTC to a Microsoft standard date-time format (COleDateTime) value. Then it formats the COleDateTime value to a string in the format %d-%b-%Y %H:%M:%S.

There are no directly applicable attributes or parameters.

ProSoftConvertDatetime

ProSoftConvertDatetime converts a four-byte native date-time to a Microsoft standard date-time format (COleDateTime) value. There are no directly applicable attributes or parameters.

ProSoftConvertDateTimeStr

ProSoftConvertDateTimeStr converts a four-byte native date-time to a Microsoft standard date-time format (COleDateTime) value. Then it formats the COleDateTime value to a string in the format %d-%b-%Y %H:%M:%S. There are no directly applicable attributes or parameters.

RealFloDateConv

RealFloDateConv converts two consecutive floating-point values to a Microsoft standard date-time format (COleDateTime) value. There are no directly applicable attributes or parameters.

SamDeviceDateTime

SamDeviceDateTime converts six two-byte integer date and time values (where two bytes represent years, two bytes represent months, two bytes represent days, two bytes represent hours, two bytes represent minutes, and two bytes represent seconds) to a Microsoft standard date-time format (COleDateTime) value. (An extraneous two-byte integer value representing day of week is not considered.) There are no directly applicable attributes or parameters.

SixByteDateTime

SixByteDateTime converts six one-byte integer date-time values (where one byte represents years, one byte represents months, one byte represents days, one byte represents hours, one byte represents minutes, and one byte represents seconds) to a Microsoft standard date-time format (COleDateTime) value. The following attributes apply to this cvtF method:

• format — See format.
• formatDate — See formatDate.

TfTime

TfTime converts a 32-bit local Unix time value to a string value or to a Microsoft standard date-time format (COleDateTime) value, depending on data type defined. The source value is read in little endian. To display the source value as a string, define type="string". To display the source value in the Microsoft standard date-time format, define type="r8". The following attributes apply to this cvtF method:

• type — See type.

TimeMs

TimeMs converts a source date-time value in number of milliseconds since January 1, 1970 (time_t) to a Microsoft standard date-time format (COleDateTime) value. Assumes an 8-byte integer representing ms. The following attributes apply to this cvtF method:

• baseTime — See baseTime.
• byteOrder — See byteOrder.
• isUTC — See isUTC.

TimeSeconds

TimeSeconds converts a source date-time value in number of seconds since January 1, 1970 (time_t) to a Microsoft standard date-time format (COleDateTime) value. (You can format the converted value using a reference data group element that defines a ref attribute and format attribute in combination.) The following attributes apply to this cvtF method:

• baseTime — See baseTime.
• byteOrder — See byteOrder.
• isUTC — See isUTC.
• wordSwap — See wordSwap.

TimeString

TimeString converts a string date-time value to a Microsoft standard date-time format (COleDateTime) value. (You can format the converted value using a reference data group element that defines a ref attribute and format attribute in combination.) The following attributes apply to this cvtF method:

• format — Valid values include "ISO8601", or strings in dateTime format.

UInt2DateTimeString

UInt2DateTimeString converts a source unsigned integer date-time value in number of seconds since January 1, 1970 (time_t) to a date-time string in the following format: DD-MM-YYYY HH:mm:ss. If no time values are returned, none are displayed. There are no directly applicable attributes or parameters.

Example

<SysStrtSec desc="Startup Date Time Secs" type="string" paramID="652" cvtF="UInt2DateTimeString"/>

Numeric Conversions

The following cvtF conversion functions all enable the conversion from one numeric format to another.

Convert12BitFloat

Convert12BitFloat converts a native twelve-bit floating-point value to a 32-bit IEEE floating-point value. Specific to Micro1c EIE devices. There are no directly applicable attributes or parameters.

Convert31BitSCompF

Convert31BitSCompF converts a negative floating-point value to a positive floating-point value by flipping the sign bit. There are no directly applicable attributes or parameters.

ConvertBCD

ConvertBCD converts a BCD (Binary-Coded Decimal) to a decimal (Base-10) integer. The following attribute applies to this cvtF method:

• parm1 — Specifies an analog input ordinal. The value must be a non-negative whole number.

Example

<BCD1A desc="Write BCD Register 1a - i2" regDef="1:0" type="i2" cvtF="ConvertBCD" parm1="1"/>

DecFloat

DecFloat converts a Digital Equipment Corporation (DEC) floating-point value to an IEEE 754 floating-point value. The following attributes apply to this cvtF method:

• wordSwap — See wordSwap. The value must be set to true.

HpFloat

HpFloat converts from a native floating-point format to an Intel floating-point format. There are no directly applicable attributes or parameters.

LufkinScaleAnalog

LufkinScaleAnalog converts an unscaled source integer to a scaled floating-point number. The conversion requires the following parameters: a manufacturer-defined minimum count scale constant of 204.6, a manufacturer-defined maximum count scale constant of 1023, a user-defined analog scale minimum value, and a user-defined analog scale maximum value. The user-defined values are configured on the field device and read by the AnlgMax and AnlgMin data elements in the ProgData data group. The values are then displayed by the ScaleMax and ScaleMin data elements in each instance of the AnalogCfg data group. A value out of count range returns 0.0. Specific to Lufkin MPC/RPC EIE and Lufkin SAM EIE devices. The following attributes apply to this cvtF method:

• parm1 — Specifies an analog input ordinal. The value must be a non-negative whole number.

LufkinScaleLoad

LufkinScaleLoad converts an unscaled source integer to a scaled floating-point number. The conversion requires the following parameters: a manufacturer-defined minimum count scale constant of 0.0, a manufacturer-defined minimum analog scale constant of 0.0, a user-defined count scale maximum value, and a user-defined analog scale maximum value. The user-defined values are configured on the field device and read by the MaxCount and MaxWeight data elements in the ProgData data group. A value out of count range returns 0.0. Specific to Lufkin MPC/RPC EIE and Lufkin SAM EIE devices. There are no directly applicable attributes or parameters.

Mod10K

Mod10K converts two consecutive two-byte big-endian register values by multiplying the first register value by 10000 and adding it to the second register value. The following attributes apply to this cvtF method:

• parm1 — Specifies whether or not the destination value is signed or unsigned. To output a signed value, set to 0. To output an unsigned value, set to 1. If parm1 is undefined, the data group element type attribute specifies the signedness of the destination value.

NuFloFWVerConv

NuFloFWVerConv converts from an integer to a version number in text in the format "n.n.n". There are no directly applicable attributes or parameters.

NuFloRegTabVerConv

NuFloRegTabVerConv converts from an integer to a version number in text in the format "n.n.n". There are no directly applicable attributes or parameters.

ProSoftAccum

ProSoftAccum converts a source eight-byte accumulator value to a destination 64-bit IEEE floating-point value. The source eight-byte value is big endian and is made up of a four-byte integer and a four-byte floating-point value. There are no directly applicable attributes or parameters.

OneByteBCDToIntelInt

OneByteBCDToIntelInt converts a one-byte, binary-coded decimal (BCD) number to a ui4 data type (four-byte unsigned integer). There are no directly applicable attributes or parameters.

Scale

Scale multiplies a source value by a multiplier. By default, the multiplier is 1. The following attributes apply to this cvtF method:

• scaleFactor — Optional, but can be used to specify a multiplier other than 1. See scaleFactor.
• sourceType — Defines the data type of the source value. See sourceType.
• type — Defines the data type of the destination value. See type.
  

Example

<GgeAgSpmAm desc="Gauge Avg Accum SPM" regNum="47541" cvtF="Scale" type="r4" sourceType="ui4" scaleFactor=".1" readOnly="true"/>

TfReg

TfReg converts a 32-bit integer value to a numeric string value in the format "n.n.n". The source value is read in little endian, where the first two bytes are converted to the leftmost n, the next byte is converted to the middle n, and the final byte is converted to the rightmost n. Typically the source value is expected to represent a register number. The following attributes apply to this cvtF method:

• type — See type.

TfStream

TfStream converts a 32-bit integer value to a numeric string stream number in the format "nnnn.nn.nn". There are no directly applicable attributes or parameters.

ThreeByteBCDToInt

ThreeByteBCDToInt converts a three-byte, binary-coded decimal(BCD) number to a ui4 data type (four-byte unsigned integer). There are no directly applicable attributes or parameters.

TLP

TLP converts a native three-byte binary TLP value into a human-readable string TLP value. There are no directly applicable attributes or parameters.

TwoByteBCDToInt

TwoByteBCDToInt converts a two-byte, binary-coded decimal (BCD) number to a ui4 data type (four-byte unsigned integer). There are no directly applicable attributes or parameters.

Version

Version converts a four-byte unsigned integer to a string value representing version. The low word represents the minor revision and revision; the high word represents the revision. Specific to FBNet EIE devices. There are no directly applicable attributes or parameters.